setup_docker: make LXC resource limits visible to nested containers - #9

✍️ Description

Inside an LXC container, Docker gives every container it starts a fresh procfs in its own mount namespace. The lxcfs bind mounts that LXC placed on /proc/meminfo and friends live in the CT's namespace and never reach it, so every Docker container reads the physical host's totals instead of the CT's limits:

CT sees:        MemTotal:  8388608 kB     # the CT's 8 GiB
container sees: MemTotal: 65648168 kB     # the whole 62 GiB hypervisor
cgroup limit:   max

Enforcement was never affected — the CT cgroup still caps every descendant. Visibility was, and anything that self-sizes from those numbers (JVM heap ergonomics, Node, Go, OpenMP thread pools) sizes against the wrong value and gets OOM-killed instead of throttling.

This registers a small runc wrapper as Docker's default-runtime. On each container create it re-binds the lxcfs-backed files into the container and, when the container sets no limit of its own, applies the CT's memory limit to the container cgroup.

Both halves are needed, because runtimes read the limit two different ways:

• glibc's sysconf(_SC_PHYS_PAGES), procps free and friends read /proc/meminfo → fixed by the binds.
• musl and Node's uv_get_constrained_memory() consult the cgroup → fixed by the limit.

CPU needs no handling: cpuset is inherited down the cgroup tree, so nested containers already observe the CT's core count. The one exception is /sys/devices/system/cpu/online, which glibc's sysconf(_SC_NPROCESSORS_ONLN) reads, so it is bound alongside the /proc files. Without it, a container on a 2-core CT reports getconf _NPROCESSORS_ONLN = 6 on a 6-core host while nproc correctly says 2 (coreutils uses sched_getaffinity).

Toggle

DOCKER_LXCFS_VISIBILITY, default true, documented in the setup_docker() header alongside the existing USE_DOCKER_REPO / DOCKER_LOG_DRIVER / DOCKER_SKIP_UPDATES. lxc-attach inherits the environment, so users opt out with:

DOCKER_LXCFS_VISIBILITY=false bash -c "$(curl -fsSL .../ct/docker.sh)"

Safety

• No-op outside an LXC container and wherever lxcfs is not mounted (guard: grep -qs 'fuse\.lxcfs' /proc/mounts), so the five non-Docker installers that call setup_docker are unaffected.
• Fails open. No runc, no jq, malformed JSON, or empty output all fall through to the real runc unmodified — worst case is current behaviour, never a dead daemon.
• runc resolved at runtime, since distro docker.io ships /usr/sbin/runc while containerd.io ships /usr/bin/runc.
• Never overrides an explicit --memory / mem_limit.
• docker run --runtime=runc bypasses the wrapper for a single container.
• Runs before systemctl enable -q --now docker, so the daemon starts with the runtime already registered — no restart needed.
• The jq merge preserves any existing daemon.json keys (registry-mirrors, insecure-registries, log-driver).

Known limitation, documented in the function header

The limit is written at container creation. After changing a CT's memory with pct set, existing containers keep the old value until recreated, or re-synced with docker update --memory=<new> --memory-swap=<new> <container>. New containers pick up the new value immediately, and CPU changes propagate live with no action.

The alternative — binds only, no cgroup limit — tracks resizes live (lxcfs walks up to the nearest ancestor with a limit) but leaves Node and musl reading the host. I judged that the worse default; happy to flip it if maintainers disagree.

🔗 Related Issue

Fixes community-scripts/ProxmoxVE#16756

✅ Prerequisites (X in brackets)

• Self-review completed – Code follows project standards.
• Tested thoroughly – Changes work as expected (Proxmox VE and/or Incus, as applicable).
• No security risks – No hardcoded secrets, unnecessary privilege escalations, or permission issues.
• API.txt regenerated – If a function signature or behavior changed, API.txt was updated to match.

🤖 AI Assistance (X in brackets)

• No AI used – Code was written without AI assistance.
• AI was used – The output has been reviewed and corrected, and I take responsibility for it matching this repo's conventions.

Model: Claude Opus 5 (1M context), reasoning effort high, via Claude Code.

🛠️ Type of Change (X in brackets)

• 🐞 Bug fix – Resolves an issue without breaking functionality.
• ✨ New feature – Adds new, non-breaking functionality.
• 💥 Breaking change – Alters existing functionality in a way that may require updates.
• 🆕 New script – A fully functional and tested script or script set.
• 🌍 Website update – Changes to script metadata (PocketBase/website data).
• 🔧 Refactoring / Code Cleanup – Improves readability or maintainability without changing functionality.
• 📝 Documentation update – Changes to README, AppName.md, CONTRIBUTING.md, or other docs.

Test evidence

Run against a real Proxmox VE 9.2.10 host (PVE kernel 7.0.14-11-pve, lxcfs 7.0.0-pve1) in an unprivileged Debian 13 CT with features: nesting=1, 8192 MB / 6 cores, Docker 29.7.2, on a 62 GiB host. The CT was reset to a clean pre-patch state, then the patched _docker_setup_lxcfs_visibility was extracted from lib/runtime.func and executed:

RED: default=runc
MemTotal:       65648168 kB
max

[info] Configuring LXC resource visibility for Docker
[ok] Configured LXC resource visibility for Docker

GREEN: default=lxcfs
MemTotal:        8388608 kB
8589934592

Additional cases, same CT:

[B --memory=1g respected]  MemTotal:  1048576 kB   memory.max: 1073741824
[C --runtime=runc bypass]  MemTotal: 65648168 kB   memory.max: max
[D cpu/online bound]       1 mount   (8 lxcfs binds total)
[E second run idempotent]  {"dr":"lxcfs","rt":["lxcfs"],"mirrors":1}
[F toggle off]             returned 0, no action taken
[G survives daemon restart] MemTotal: 8388608 kB   memory.max: 8589934592

Note [B]: lxcfs resolves per reading process's cgroup, so a container with its own --memory reports its limit through the same bind — no per-container wiring needed.

CI gates run locally:

shellcheck --shell=bash --severity=error --exclude=SC1091 --format=gcc lib/runtime.func   -> rc=0
shellcheck --severity=warning, added range                                               -> clean
verify-split-files API check: lib/tools.func vs lib/API.txt                               -> matches (151 functions)

Verification one-liner for reviewers

echo "CT sees:        $(head -1 /proc/meminfo)"
echo "container sees: $(docker run --rm alpine head -1 /proc/meminfo)"
echo "cgroup limit:   $(docker run --rm alpine cat /sys/fs/cgroup/memory.max)"

Two commands that look fine while this is broken, worth avoiding: docker info reports the correct MemTotal throughout, because the daemon is a plain CT process reading lxcfs; and docker run --rm alpine free -m prints the host figure even once fixed, because busybox free uses sysinfo(2), which lxcfs cannot intercept.